***************
Getting started
***************

Users have access to a Python API which allows them to locally construct simulation scripts.
See the commented demo script example :doc:`here <tutorials/demo_example>`.

Installation
------------

It can be installed as follows:

.. code:: console

    pip install neurodec

The installed API allows communication with a server where all the computations are done.
For this, the user should be authenticated.
You will be provided a file with credentials, named `credentials` (no extension).
Place this file in the directory `~/.config/neurodec/mdt/`, i.e.,

.. code:: console

    mkdir -p  ~/.config/neurodec/mdt
    mv credentials ~/.config/neurodec/mdt

The main API principles
-----------------------

Classes
"""""""

At each :doc:`simulation step <tutorials/simulation pipeline>`, users need to create an instance of the corresponding class, providing necessary input data/parameters.

.. code:: ipython3

    ## Create a Surface object for a skin from a surface mesh
    skin_surface = nd.mdt.Surface.new(vertices, triangles, nd.mdt.SurfaceType.OUTER_SKIN)

After the object is created, it sends a computation request to the server which is then added to a queue.
The results of the computation will be stored in the database along with the corresponding object.

It's important to note that there is a one-to-one correspondence between the received input and the object id stored in the database.
This means that if you attempt to do a simulation step with inputs that have already been used, the object will be loaded from the database and no recomputation will be necessary.

Object status
"""""""""""""

Each object has ``id`` and ``status`` attributes. Some objects can have additional class-specific attributes.

Status.PENDING means that the corresponding computation is scheduled.

Status.PROCESSING means that the corresponding computation is still ongoing.

Status.READY means that the computation is finished and the results are stored in database

.. code:: ipython3

    print(skin_surface.id, skin_surface.status)

.. parsed-literal::

    'Surface(1, Status.READY)'

Script running mode
"""""""""""""""""""

User have two different ways of running jupyter notebook scripts.

#. Run the script step by step, i.e., wait for the previous step to complete before running the next one. This replicates the usual way how jupyter notebook works.

#. Send all the instruction to server, without waiting for computation results. This approach allows users to "decouple" the computations from the local machine.

This mode is controlled by the ``neurodec.mdt.wait`` parameter:

.. code:: ipython3

    nd.mdt.wait = True  # Set to true to wait step by step.

Data access
"""""""""""

For some objects, you may need to access the result of the computation. This can be done using the corresponding class method like this:

.. code:: ipython3

    emg_object = nd.mdt.Electromyography.new(impulse_trains)
    emg_data = emg.data

It's important to note that when you access the result in this way, the data will be downloaded from the server and stored in RAM.